<?xml version="1.0" encoding="UTF-8"?>
<html filename="docs/SAXHelpers/TNamespaceSupport.html">
<body>
<a id="#top"/>
<h1>
	                Class Summary : TNamespaceSupport </h1> Encapsulate Namespace logic for use by applications using SAX,
 or internally by SAX drivers.

 <blockquote>
 <em>This module, both source code and documentation, is in the
 Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
 </blockquote>

 <p>This class encapsulates the logic of Namespace processing:
 it tracks the declarations currently in force for each context
 and automatically processes qualified XML 1.0 names into their
 Namespace parts; it can also be used in reverse for generating
 XML 1.0 from Namespaces.</p>

 <p>Namespace support objects are reusable, but the reset method
 must be invoked between each session.</p>

 <p>Here is a simple session:</p>

 <pre>
 var parts : TNamespaceParts;
     support : TNamespaceSupport;
 begin
   SetLength(parts, 3);
   support:= TNamespaceSupport.Create();

 support.pushContext();
 support.declarePrefix('', 'http://www.w3.org/1999/xhtml&quot;';
 support.declarePrefix('dc', 'http://www.purl.org/dc#');

 parts:= support.processName('p', parts, false);
 Showmessage('Namespace URI: ' + parts[0]);
 Showmessage('Local name: ' + parts[1]);
 Showmessage('Raw name: ' + parts[2]);
 parts:= support.processName('dc:title', parts, false);
 Showmessage('Namespace URI: ' + parts[0]);
 Showmessage('Local name: ' + parts[1]);
 Showmessage('Raw name: ' + parts[2]);
 support.popContext();
 </pre>

 <p>Note that this class is optimized for the use case where most
 elements do not contain Namespace declarations: if the same
 prefix/URI mapping is repeated for each context (for example), this
 class will be somewhat less efficient.</p>
 <p>Although SAX drivers (parsers) may choose to use this class to
 implement namespace handling, they are not required to do so.
 Applications must track namespace information themselves if they
 want to use namespace information.</p>

<br/><b>Since : </b> SAX 2.0
<h2>
	              Methods
	            </h2>
<div style="padding-left:10px">
<a href="#freeContexts">
	                  procedure
	                 freeContexts()</a>
<br/>
<a href="#reset">
	                  procedure
	                 reset()</a>
<br/>
<a href="#pushContext">
	                  procedure
	                 pushContext()</a>
<br/>
<a href="#popContext">
	                  procedure
	                 popContext()</a>
<br/>
<a href="#declarePrefix">
	                  function
	                 declarePrefix(SAXString, SAXString) : Boolean</a>
<br/>
<a href="#declarePrefix">
	                  function
	                 declarePrefix(PSAXChar, Integer, PSAXChar, Integer) : Boolean</a>
<br/>
<a href="#processName">
	                  function
	                 processName(SAXString, TNamespaceParts, Boolean) : TNamespaceParts</a>
<br/>
<a href="#processName">
	                  function
	                 processName(PSAXChar, Integer, TNamespaceParts, Boolean) : TNamespaceParts</a>
<br/>
<a href="#getURI">
	                  function
	                 getURI(SAXString) : SAXString</a>
<br/>
<a href="#getURI">
	                  function
	                 getURI(PSAXChar, Integer) : PSAXChar</a>
<br/>
<a href="#getPrefixes">
	                  function
	                 getPrefixes() : SAXStringArray</a>
<br/>
<a href="#getPrefix">
	                  function
	                 getPrefix(SAXString) : SAXString</a>
<br/>
<a href="#getPrefix">
	                  function
	                 getPrefix(PSAXChar, Integer) : PSAXChar</a>
<br/>
<a href="#getPrefixes">
	                  function
	                 getPrefixes(SAXString) : SAXStringArray</a>
<br/>
<a href="#getPrefixes">
	                  function
	                 getPrefixes(PSAXChar, Integer) : SAXStringArray</a>
<br/>
<a href="#getDeclaredPrefixes">
	                  function
	                 getDeclaredPrefixes() : SAXStringArray</a>
<br/>
<a href="#setNamespaceDeclUris">
	                  procedure
	                 setNamespaceDeclUris(Boolean)</a>
<br/>
<a href="#isNamespaceDeclUris">
	                  function
	                 isNamespaceDeclUris() : Boolean</a>
<br/>
</div>
<br/>
<hr width="100%"/>
<a name="#freeContexts">
<p>
<b>procedure</b> freeContexts(); </p>
</a> Internal method for destroying the Contexts that are created by this
 class

<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#destroy">TNamespaceSupport.destroy</a>
<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#reset">TNamespaceSupport.reset</a>
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#reset">
<p>
<b>procedure</b> reset(); </p>
</a> Reset this Namespace support object for reuse.

 <p>It is necessary to invoke this method before reusing the
 Namespace support object for a new session.  If namespace
 declaration URIs are to be supported, that flag must also
 be set to a non-default value.
 </p>

<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#setNamespaceDeclUris">TNamespaceSupport.setNamespaceDeclUris</a>
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#pushContext">
<p>
<b>procedure</b> pushContext(); </p>
</a> Start a new Namespace context.

 The new context will automatically inherit
 the declarations of its parent context, but it will also keep
 track of which declarations were made within this context.

 <p>Event callback code should start a new context once per element.
 This means being ready to call this in either of two places.
 For elements that don't include namespace declarations, the
 <em>ContentHandler.startElement()</em> callback is the right place.
 For elements with such a declaration, it'd done in the first
 <em>ContentHandler.startPrefixMapping()</em> callback.
 A boolean flag can be used to
 track whether a context has been started yet.  When either of
 those methods is called, it checks the flag to see if a new context
 needs to be started.  If so, it starts the context and sets the
 flag.  After <em>ContentHandler.startElement()</em>
 does that, it always clears the flag.</p>

 <p>Normally, SAX drivers would push a new context at the beginning
 of each XML element.  Then they perform a first pass over the
 attributes to process all namespace declarations, making
 <em>ContentHandler.startPrefixMapping()</em> callbacks.
 Then a second pass is made, to determine the namespace-qualified
 names for all attributes and for the element name.
 Finally all the information for the
 <em>ContentHandler.startElement()</em> callback is available,
 so it can then be made.</p>
 <p>The Namespace support object always starts with a base context
 already in force: in this context, only the 'xml' prefix is
 declared.</p>

<br/><b>See : </b> <a href="../SAX/IContentHandler.html">IContentHandler</a>
<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#popContext">TNamespaceSupport.popContext</a>
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#popContext">
<p>
<b>procedure</b> popContext(); </p>
</a> Revert to the previous Namespace context.

 <p>Normally, you should pop the context at the end of each
 XML element.  After popping the context, all Namespace prefix
 mappings that were previously in force are restored.</p>

 <p>You must not attempt to declare additional Namespace
 prefixes after popping a context, unless you push another
 context first.</p>

<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#pushContext">TNamespaceSupport.pushContext</a>
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#declarePrefix">
<p>
<b>function</b> declarePrefix(<b>const</b> prefix : SAXString; <b>const</b> uri : SAXString) : Boolean; </p>
</a> Declare a Namespace prefix.  All prefixes must be declared
 before they are referenced.  For example, a SAX driver (parser)
 would scan an element's attributes
 in two passes:  first for namespace declarations,
 then a second pass using <a href="../SAXHelpers/TNamespaceSupport.html#processName">processName</a> to
 interpret prefixes against (potentially redefined) prefixes.

 <p>This method declares a prefix in the current Namespace
 context; the prefix will remain in force until this context
 is popped, unless it is shadowed in a descendant context.</p>

 <p>To declare the default element Namespace, use the empty string as
 the prefix.</p>

 <p>Note that you must <em>not</em> declare a prefix after
 you've pushed and popped another Namespace.</p>

 <p>Note that you must <em>not</em> declare a prefix after
 you've pushed and popped another Namespace context, or
 treated the declarations phase as complete by processing
 a prefixed name.</p>

 <p>Note that there is an asymmetry in this library:
 <a href="../SAXHelpers/TNamespaceSupport.html#getPrefix">getPrefix</a>
 will not return the &quot;&quot; prefix,
 even if you have declared a default element namespace.
 To check for a default namespace,
 you have to look it up explicitly using <a href="../SAXHelpers/TNamespaceSupport.html#getURI">getURI</a>.
 This asymmetry exists to make it easier to look up prefixes
 for attribute names, where the default prefix is not allowed.</p>

<br/><b>Parameter : </b> prefix The prefix to declare, or the empty string to
	indicate the default element namespace.  This may never have
	the value &quot;xml&quot; or &quot;xmlns&quot;.
<br/><b>Parameter : </b> uri The Namespace URI to associate with the prefix.
<br/><b>Result : </b> true if the prefix was legal, false otherwise
<br/><b>Exception : </b> ESAXIllegalStateException when a prefix is declared
	after looking up a name in the context, or after pushing
	another context on top of it.

<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#processName">TNamespaceSupport.processName</a>
<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#getURI">TNamespaceSupport.getURI</a>
<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#getPrefix">TNamespaceSupport.getPrefix</a>
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#declarePrefix">
<p>
<b>function</b> declarePrefix( prefix : PSAXChar;  prefixLength : Integer;  uri : PSAXChar;  uriLength : Integer) : Boolean; </p>
</a> Declare a Namespace prefix.

<br/><b>Parameter : </b> prefix The prefix to declare, or the empty string to
	indicate the default element namespace.  This may never have
	the value &quot;xml&quot; or &quot;xmlns&quot;.
<br/><b>Parameter : </b> prefixLength The length of the prefix buffer
   The value may be -1 which indicates that the buffer is
   null-terminated. If the value is 0 then the buffer may be nil.
<br/><b>Parameter : </b> uri The Namespace URI to associate with the prefix.
<br/><b>Parameter : </b> uriLength The length of the uri buffer
   The value may be -1 which indicates that the buffer is
   null-terminated. If the value is 0 then the buffer may be nil.
<br/><b>Result : </b> true if the prefix was legal, false otherwise
<br/><b>Exception : </b> ESAXIllegalStateException when a prefix is declared
	after looking up a name in the context, or after pushing
	another context on top of it.
<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#declarePrefix.SAXString. SAXString">TNamespaceSupport.declarePrefix(SAXString, SAXString)</a>
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#processName">
<p>
<b>function</b> processName(<b>const</b> qName : SAXString; <b>var</b> parts : TNamespaceParts;  isAttribute : Boolean) : TNamespaceParts; </p>
</a> Process a raw XML 1.0 name, after all declarations in the current
 context have been handled by <a href="../SAXHelpers/TNamespaceSupport.html#declarePrefix">declarePrefix</a>.

 <p>This method processes a raw XML 1.0 name in the current
 context by removing the prefix and looking it up among the
 prefixes currently declared.  The return value will be the
 array supplied by the caller, filled in as follows:</p>

 <dl>
 <dt>parts[0]</dt>
 <dd>The Namespace URI, or an empty string if none is
  in use.</dd>
 <dt>parts[1]</dt>
 <dd>The local name (without prefix).</dd>
 <dt>parts[2]</dt>
 <dd>The original raw name.</dd>
 </dl>

 <p>If the raw name has a prefix that has not been declared, then
 the return value will be an empty string.</p>

 <p>Note that attribute names are processed differently than
 element names: an unprefixed element name will receive the
 default Namespace (if any), while an unprefixed attribute name
 will not.</p>

<br/><b>Parameter : </b> qName The raw XML 1.0 name to be processed.
<br/><b>Parameter : </b> parts An array supplied by the caller, capable of
        holding at least three members.
<br/><b>Parameter : </b> isAttribute A flag indicating whether this is an
        attribute name (true) or an element name (false).
<br/><b>Result : </b> The supplied array holding three internalized strings
        representing the Namespace URI (or empty string), the
        local name, and the raw XML 1.0 name; or '' if there
        is an undeclared prefix.
<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#declarePrefix">TNamespaceSupport.declarePrefix</a>
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#processName">
<p>
<b>function</b> processName( qName : PSAXChar;  qNameLength : Integer; <b>var</b> parts : TNamespaceParts;  isAttribute : Boolean) : TNamespaceParts; </p>
</a> Process a raw XML 1.0 name, after all declarations in the current
 context have been handled by <a href="../SAXHelpers/TNamespaceSupport.html#declarePrefix">declarePrefix</a>.

<br/><b>Parameter : </b> qName The raw XML 1.0 name to be processed.
<br/><b>Parameter : </b> qNameLength The length of the qName buffer
   The value may be -1 which indicates that the buffer is
   null-terminated. If the value is 0 then the buffer may be nil.
<br/><b>Parameter : </b> parts An array supplied by the caller, capable of
        holding at least three members.
<br/><b>Parameter : </b> isAttribute A flag indicating whether this is an
        attribute name (true) or an element name (false).
<br/><b>Result : </b> The supplied array holding three internalized strings
        representing the Namespace URI (or empty string), the
        local name, and the raw XML 1.0 name; or '' if there
        is an undeclared prefix.
<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#declarePrefix.SAXString.TNamespaceParts.Boolean">TNamespaceSupport.declarePrefix(SAXString, TNamespaceParts, Boolean)</a>
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#getURI">
<p>
<b>function</b> getURI(<b>const</b> prefix : SAXString) : SAXString; </p>
</a> Look up a prefix and get the currently-mapped Namespace URI.

 <p>This method looks up the prefix in the current context.
 Use the empty string ('') for the default Namespace.</p>

<br/><b>Parameter : </b> prefix The prefix to look up.
<br/><b>Result : </b> The associated Namespace URI, or an empty string if the prefix
         is undeclared in this context.
<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#getPrefix">TNamespaceSupport.getPrefix</a>
<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#getPrefixes">TNamespaceSupport.getPrefixes</a>
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#getURI">
<p>
<b>function</b> getURI( prefix : PSAXChar;  prefixLength : Integer) : PSAXChar; </p>
</a> Look up a prefix and get the currently-mapped Namespace URI.

<br/><b>Parameter : </b> prefix The prefix to look up.
<br/><b>Parameter : </b> prefixLength The length of the prefix buffer
   The value may be -1 which indicates that the buffer is
   null-terminated. If the value is 0 then the buffer may be nil.
<br/><b>Result : </b> The associated Namespace URI, or an empty string if the prefix
         is undeclared in this context.
<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#getURI.SAXString">TNamespaceSupport.getURI(SAXString)</a>
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#getPrefixes">
<p>
<b>function</b> getPrefixes() : SAXStringArray; </p>
</a> Return an enumeration of all prefixes whose declarations are
 active in the current context.
 This includes declarations from parent contexts that have
 not been overridden.

 <p>
      <strong>Note:</strong> if there is a default prefix, it will not be
 returned in this enumeration; check for the default prefix
 using the <a href="../SAXHelpers/TNamespaceSupport.html#getURI">getURI</a> with an argument of ''.</p>

<br/><b>Result : </b> An enumeration of prefixes (never empty).

<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#getDeclaredPrefixes">TNamespaceSupport.getDeclaredPrefixes</a>
<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#getURI">TNamespaceSupport.getURI</a>
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#getPrefix">
<p>
<b>function</b> getPrefix(<b>const</b> uri : SAXString) : SAXString; </p>
</a> Return one of the prefixes mapped to a Namespace URI.

 <p>If more than one prefix is currently mapped to the same
 URI, this method will make an arbitrary selection; if you
 want all of the prefixes, use the <a href="../SAXHelpers/TNamespaceSupport.html#getPrefixes">getPrefixes</a>
 method instead.</p>

 <p>
      <strong>Note:</strong> this will never return the empty (default) prefix;
 to check for a default prefix, use the <a href="../SAXHelpers/TNamespaceSupport.html#getURI">getURI</a>
 method with an argument of ''.</p>

<br/><b>Parameter : </b> uri The Namespace URI.
<br/><b>Parameter : </b> isAttribute true if this prefix is for an attribute
        (and the default Namespace is not allowed).
<br/><b>Result : </b> One of the prefixes currently mapped to the URI supplied,
         or an empty string if none is mapped or if the URI is assigned to
         the default Namespace.
<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#getPrefixes.SAXString">TNamespaceSupport.getPrefixes(SAXString)</a>
<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#getURI">TNamespaceSupport.getURI</a>
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#getPrefix">
<p>
<b>function</b> getPrefix( uri : PSAXChar;  uriLength : Integer) : PSAXChar; </p>
</a> Return one of the prefixes mapped to a Namespace URI.

<br/><b>Parameter : </b> uri The Namespace URI.
<br/><b>Parameter : </b> uriLength The length of the uri buffer
   The value may be -1 which indicates that the buffer is
   null-terminated. If the value is 0 then the buffer may be nil.
<br/><b>Parameter : </b> isAttribute true if this prefix is for an attribute
        (and the default Namespace is not allowed).
<br/><b>Result : </b> One of the prefixes currently mapped to the URI supplied,
         or an empty string if none is mapped or if the URI is assigned to
         the default Namespace.
<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#getPrefix.SAXString">TNamespaceSupport.getPrefix(SAXString)</a>
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#getPrefixes">
<p>
<b>function</b> getPrefixes(<b>const</b> uri : SAXString) : SAXStringArray; </p>
</a> Return an enumeration of all prefixes for a given URI whose
 declarations are active in the current context.
 This includes declarations from parent contexts that have
 not been overridden.

 <p>This method returns prefixes mapped to a specific Namespace
 URI.  The xml: prefix will be included.  If you want only one
 prefix that's mapped to the Namespace URI, and you don't care
 which one you get, use the <a href="../SAXHelpers/TNamespaceSupport.html#getPrefix">getPrefix</a>
 method instead.</p>

 <p>
      <strong>Note:</strong> the empty (default) prefix is <em>never</em> included
 in this enumeration; to check for the presence of a default
 Namespace, use the <a href="../SAXHelpers/TNamespaceSupport.html#getURI">getURI</a> method with an
 argument of ''.</p>

<br/><b>Parameter : </b> uri The Namespace URI.
<br/><b>Result : </b> An enumeration of prefixes (never empty).

<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#getPrefix">TNamespaceSupport.getPrefix</a>
<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#getDeclaredPrefixes">TNamespaceSupport.getDeclaredPrefixes</a>
<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#getURI">TNamespaceSupport.getURI</a>
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#getPrefixes">
<p>
<b>function</b> getPrefixes( uri : PSAXChar;  uriLength : Integer) : SAXStringArray; </p>
</a> Return an enumeration of all prefixes currently declared for a URI.

<br/><b>Parameter : </b> uri The Namespace URI.
<br/><b>Parameter : </b> uriLength The length of the uri buffer
   The value may be -1 which indicates that the buffer is
   null-terminated. If the value is 0 then the buffer may be nil.
<br/><b>Result : </b> An enumeration of all prefixes declared in the
         current context.
<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#getPrefixes.SAXString">TNamespaceSupport.getPrefixes(SAXString)</a>
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#getDeclaredPrefixes">
<p>
<b>function</b> getDeclaredPrefixes() : SAXStringArray; </p>
</a> Return an enumeration of all prefixes declared in this context.

 <p>The empty (default) prefix will be included in this
 enumeration; note that this behaviour differs from that of
 <a href="../SAXHelpers/TNamespaceSupport.html#getPrefix">getPrefix</a> and
 <a href="../SAXHelpers/TNamespaceSupport.html#getPrefixes">getPrefixes</a>.</p>

<br/><b>Result : </b> An enumeration of all prefixes declared in this
         context.
<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#getPrefixes">TNamespaceSupport.getPrefixes</a>
<br/><b>See : </b> <a href="../SAXHelpers/TNamespaceSupport.html#getURI">TNamespaceSupport.getURI</a>
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#setNamespaceDeclUris">
<p>
<b>procedure</b> setNamespaceDeclUris( value : Boolean); </p>
</a> Controls whether namespace declaration attributes are placed
 into the <code>http://www.w3.org/xmlns/2000/</code> namespace
 by <a href="../SAXHelpers/TNamespaceSupport.html#processName">processName</a>.  This may only be
 changed before any contexts have been pushed.

<br/><b>Since : </b> SAX 2.1 alpha

<br/><b>Exception : </b> EIllegalStateException when attempting to set this
  after any context has been pushed.
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#isNamespaceDeclUris">
<p>
<b>function</b> isNamespaceDeclUris() : Boolean; </p>
</a> Returns true if namespace declaration attributes are placed into
 a namespace.  This behavior is not the default.

<br/><b>Since : </b> SAX 2.1 alpha
/
<br/>
<p>
<a href="#top">Top</a>
</p>
</body>
</html>